App Events#

The AppEvents module in the Scripting app provides an interface to observe global application state changes, such as scene lifecycle transitions and changes in system-wide appearance (light/dark mode). These capabilities are essential for writing responsive scripts that react appropriately to runtime context.

Scene Lifecycle#

ScenePhase#

1type ScenePhase = 'active' | 'inactive' | 'background'

Represents the state of the app’s scene:

• active – The app is in the foreground and interactive.
• inactive – The app is in transition or temporarily inactive.
• background – The app is running in the background and not visible.

Color Scheme#

ColorScheme#

1type ColorScheme = 'light' | 'dark'

Reflects the current appearance mode of the device:

• light – Light mode UI
• dark – Dark mode UI

AppEventListenerManager<T>#

1class AppEventListenerManager<T> {
2  addListener(listener: (data: T) => void): void
3  removeListener(listener: (data: T) => void): void
4}

A generic event manager that allows you to register and unregister listeners dynamically. Used for both scenePhase and colorScheme.

AppEvents Class#

1class AppEvents {
2  static scenePhase: AppEventListenerManager<ScenePhase>
3  static colorScheme: AppEventListenerManager<ColorScheme>
4}

AppEvents.scenePhase#

Listen for scene phase transitions. Ideal for responding to foreground/background state changes.

Example#

1AppEvents.scenePhase.addListener((phase) => {
2  if (phase === 'active') {
3    console.log("App is active")
4  } else if (phase === 'background') {
5    console.log("App is in background")
6  }
7})

AppEvents.colorScheme#

Observe system-wide light/dark appearance changes in real time.

Example#

1AppEvents.colorScheme.addListener((scheme) => {
2  console.log(`Current color scheme: ${scheme}`)
3})

useColorScheme() Hook#

1declare function useColorScheme(): ColorScheme

Description#

This hook provides a reactive way to access the current ColorScheme ('light' or 'dark') within a component. It automatically updates the value when the system theme changes.

Example#

1function ThemedView() {
2  const colorScheme = useColorScheme()
3
4  return <Text>
5    {colorScheme === 'dark' ? 'Dark Mode Active' : 'Light Mode Active'}
6  </Text>
7}

Notes#

• Listeners registered with AppEvents should be manually removed when no longer needed to prevent memory leaks.
• useColorScheme() is the recommended way to reactively reflect the current theme in your components.
• These APIs allow you to respond to system and app-level state changes in a clean, declarative way—without relying on imperative lifecycle logic.